home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / catD / kmem_alloc.z / kmem_alloc
Encoding:
Text File  |  2002-10-03  |  7.5 KB  |  132 lines
  1.  
  2.  
  3.  
  4. kkkkmmmmeeeemmmm____aaaalllllllloooocccc((((DDDD3333))))                                                  kkkkmmmmeeeemmmm____aaaalllllllloooocccc((((DDDD3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      _kkkk_mmmm_eeee_mmmm______aaaa_llll_llll_oooo_cccc - allocate space from kernel free memory
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_tttt_yyyy_pppp_eeee_ssss_...._hhhh_>>>>
  13.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_kkkk_mmmm_eeee_mmmm_...._hhhh_>>>>
  14.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_dddd_dddd_iiii_...._hhhh_>>>>
  15.      _vvvv_oooo_iiii_dddd _****_kkkk_mmmm_eeee_mmmm______aaaa_llll_llll_oooo_cccc_((((_ssss_iiii_zzzz_eeee______tttt _s_i_z_e_,,,, _iiii_nnnn_tttt _f_l_a_g_))))_;;;;
  16.  
  17.    AAAArrrrgggguuuummmmeeeennnnttttssss
  18.      _s_i_z_e      Number of bytes to allocate.
  19.  
  20.      _f_l_a_g      Specifies whether the caller is willing to sleep waiting for
  21.                memory, etc.
  22.  
  23. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  24.      _kkkk_mmmm_eeee_mmmm______aaaa_llll_llll_oooo_cccc allocates _s_i_z_e bytes of kernel memory and returns a pointer to
  25.      the allocated memory.  If _f_l_a_g is set to _KKKK_MMMM______SSSS_LLLL_EEEE_EEEE_PPPP, the caller will sleep
  26.      if necessary until the specified amount of memory is available.  If _f_l_a_g
  27.      is set to _KKKK_MMMM______NNNN_OOOO_SSSS_LLLL_EEEE_EEEE_PPPP, the caller will not sleep, but _kkkk_mmmm_eeee_mmmm______aaaa_llll_llll_oooo_cccc will
  28.      return _NNNN_UUUU_LLLL_LLLL if the specified amount of memory is not immediately
  29.      available. _KKKK_MMMM______PPPP_HHHH_YYYY_SSSS_CCCC_OOOO_NNNN_TTTT_IIII_GGGG:  Allocate contiguous physical memory.
  30.  
  31.      _CCCC_AAAA_UUUU_TTTT_IIII_OOOO_NNNN_:::: It is best to call _kkkk_mmmm_eeee_mmmm______aaaa_llll_llll_oooo_cccc with this flag _o_n_l_y at driver
  32.      initialization time. Otherwise, it may sleep for a very long time.
  33.  
  34.      _KKKK_MMMM______CCCC_AAAA_CCCC_HHHH_EEEE_AAAA_LLLL_IIII_GGGG_NNNN_:::: Allocate the requested memory starting at a cache line
  35.      boundary. This also pads the buffer out to a full cache line. Buffers
  36.      that the driver will use for _DDDD_MMMM_AAAA must be cache-line aligned and padded to
  37.      a full cache line.
  38.  
  39.    RRRReeeettttuuuurrrrnnnn VVVVaaaalllluuuueeeessss
  40.      Upon successful completion, _kkkk_mmmm_eeee_mmmm______aaaa_llll_llll_oooo_cccc returns a pointer to the allocated
  41.      memory.  If _KKKK_MMMM______NNNN_OOOO_SSSS_LLLL_EEEE_EEEE_PPPP is specified and sufficient memory is not
  42.      immediately available, _kkkk_mmmm_eeee_mmmm______aaaa_llll_llll_oooo_cccc returns a _NNNN_UUUU_LLLL_LLLL pointer.  If _s_i_z_e is set
  43.      to _0000, _kkkk_mmmm_eeee_mmmm______aaaa_llll_llll_oooo_cccc returns _NNNN_UUUU_LLLL_LLLL regardless of the value of _f_l_a_g.
  44.  
  45. UUUUSSSSAAAAGGGGEEEE
  46.      Kernel memory is a limited resource and should be used judiciously.
  47.      Memory allocated using _kkkk_mmmm_eeee_mmmm______aaaa_llll_llll_oooo_cccc should be freed as soon as possible.
  48.      Drivers should not use local freelists for memory or similar schemes that
  49.      cause the memory to be held for longer than necessary.
  50.  
  51.      Since holding memory allocated using _kkkk_mmmm_eeee_mmmm______aaaa_llll_llll_oooo_cccc for extended periods of
  52.      time (e.g allocating memory at system startup and never freeing it) can
  53.      have an adverse effect on overall memory usage and system performance,
  54.      memory needed for such extended periods should be statically allocated
  55.      whenever possible.
  56.  
  57.  
  58.  
  60.  
  61.  
  62.                                                                         PPPPaaaaggggeeee 1111
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69. kkkkmmmmeeeemmmm____aaaalllllllloooocccc((((DDDD3333))))                                                  kkkkmmmmeeeemmmm____aaaalllllllloooocccc((((DDDD3333))))
  70.  
  71.  
  72.  
  73.      The address returned by a successful call to _kkkk_mmmm_eeee_mmmm______aaaa_llll_llll_oooo_cccc is word-aligned.
  74.  
  75.    LLLLeeeevvvveeeellll
  76.      Base only if _f_l_a_g is set to _KKKK_MMMM______SSSS_LLLL_EEEE_EEEE_PPPP.
  77.  
  78.      Initialization, Base or Interrupt if _f_l_a_g is set to _KKKK_MMMM______NNNN_OOOO_SSSS_LLLL_EEEE_EEEE_PPPP.
  79.  
  80.    SSSSyyyynnnncccchhhhrrrroooonnnniiiizzzzaaaattttiiiioooonnnn CCCCoooonnnnssssttttrrrraaaaiiiinnnnttttssss
  81.      May sleep if _f_l_a_g is set to _KKKK_MMMM______SSSS_LLLL_EEEE_EEEE_PPPP.
  82.  
  83.      Driver-defined basic locks and read/write locks may be held across calls
  84.      to this function if _f_l_a_g is _KKKK_MMMM______NNNN_OOOO_SSSS_LLLL_EEEE_EEEE_PPPP, but may not be held if _f_l_a_g is
  85.      _KKKK_MMMM______SSSS_LLLL_EEEE_EEEE_PPPP.
  86.  
  87.      Driver-defined sleep locks may be held across calls to this function
  88.      regardless of the value of _f_l_a_g.
  89.  
  90.    NNNNooootttteeee
  91.      _kkkk_mmmm_eeee_mmmm______aaaa_llll_llll_oooo_cccc and _kkkk_mmmm_eeee_mmmm______ffff_rrrr_eeee_eeee are intended as replacements for _kkkk_eeee_rrrr_nnnn______mmmm_aaaa_llll_llll_oooo_cccc and
  92.      _kkkk_eeee_rrrr_nnnn______ffff_rrrr_eeee_eeee.  Drivers should use these routines rather than _kkkk_eeee_rrrr_nnnn______mmmm_aaaa_llll_llll_oooo_cccc and
  93.      _kkkk_eeee_rrrr_nnnn______ffff_rrrr_eeee_eeee.
  94.  
  95. RRRREEEEFFFFEEEERRRREEEENNNNCCCCEEEESSSS
  96.      _kkkk_mmmm_eeee_mmmm______ffff_rrrr_eeee_eeee(D3), _kkkk_mmmm_eeee_mmmm______zzzz_aaaa_llll_llll_oooo_cccc(D3), Appendix A, Section A.2, "Data cache
  97.      Write Back and Invalidation" of the _I_R_I_X _D_e_v_i_c_e _D_r_i_v_e_r _P_r_o_g_r_a_m_m_i_n_g _G_u_i_d_e
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.                                                                         PPPPaaaaggggeeee 2222
  129.  
  130.  
  131.  
  132.